REST와 REST API

✒️ 2025-06-24 17:25 내용 수정

스프링부트3 자바 백엔드 개발입문 내용 참고 및 정리

참고 자료 : 위키백과 REST, NHN Cloud NHN REST API 제대로 알고 사용하기, Inpa dev's REST API 구성/특징 총 정리

REST(Representational State Transfer)

분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처

• 네트워크 아키텍처 원리(자원을 정의하고 자원에 대한 주소를 지정하는 방법의 전반) 의 모음을 의미한다.
• 자원을 정의하고, 자원에 대한 행위(전송, 처리 등)를 표현하는 아키텍처다.

REST 아키텍처에 적용되는 제한 조건

1. 인터페이스 일관성(uniform)
   • 일관적인 인터페이스로 분리되어야 한다.
   • URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 의미한다.
2. 무상태(Stateless)
   • 각 요청 간 클라이언트의 Context가 서버에 저장되어선 안된다.
   • 작업을 위한 상태 정보를 따로 저장하고 관리하지 않고, 들어오는 요청만 단순히 처리한다.
3. 캐시 가능(Cacheable)
   • HTTP 웹 표준을 그대로 사용하기에 클라이언트는 응답을 캐싱할 수 있다.
4. 계층화(Layered System)
   • REST 서버는 다중 계층으로 구성될 수 있어 클라이언트가 대상 서버에 직접 연결되거나 중간 서버를 통해 연결될 수 있다.
   • 중간 서버는 로드 밸런싱이나 PROXY, 게이트웨이, 공유 캐시 기능을 제공하여 시스템 규모의 확장성을 향상시키는데 사용될 수 있다.
5. Code on demand
   • 선택 사항으로, Java applet이나 Javascript 제공을 통해 서버가 클라이언트를 실행시킬 수 있는 로직을 전송하여 기능을 확장시킬 수 있다.
6. 클라이언트/서버 구조
   • 아키텍처를 단순화시키고 작은 단위로 분리하여 클라이언트-서버의 각 파트가 독립적으로 개선될 수 있다. 또한 이 구조를 사용하여 클라이언트와 서버의 의존성이 줄어든다.

REST 인터페이스 원칙

1. 자원 식별
   • 요청에 기술된 개별 자원을 식별할 수 있어야 한다.
   • URI 사용의 경우 정보의 자원을 표현하고 행위와 같은 표현은 들어가면 안된다.
2. 메시지를 통한 리소스의 조작
   • 클라이언트가 어떤 자원을 지칭하는 메시지와 특정 메타 데이터만 가지고 있는 경우, 이 메시지나 메타 데이터로 서버 상의 해당 자원을 변경/삭제할 수 있도록 해야 한다.
   • 즉 메시지를 통해 서버의 리소스를 조작할 수 있다.
3. 자기서술적 메시지
   • 각 메시지는 자신을 어떻게 처리해야 하는지에 대한 충분한 정보를 포함해야 한다.
   • 메시지를 이해하기 위해 그 내용까지 살펴봐야 한다면 이는 자기서술적 메시지가 아니며, 메시지만 보고 응답을 어떻게 처리해야 하는지 알 수 있어야 한다.
   • 따라서 행위에 따른 HTTP 메서드를 따라 설계한다.
   • 또한 응답에 HTTP 상태 코드를 포함하여 응답의 상태를 명확하게 표현해야 한다.
4. 무상태성 유지
   • 각 요청은 모두 독립적이며, 서버는 클라이언트의 상태를 저장하지 않는다.
5. 자원 간 계층 구조 유지
   • /users/1/order/10 : 1번 사용자의 주문 중 10번 주문

REST API

• REST 아키텍처를 적용한 API(Application Programming Interface) 이다.
• 서버의 자원을 클라이언트에 구애 받지 않고 사용할 수 있게 설계할 수 있다.
• HTTP 요청에 대한 응답으로 JSON 데이터를 반환한다.
  • 예전에는 XML(Extension Markup Language)를 자주 사용했으나 최근에는 JSON(Javascript Object Notation)을 주로 사용한다.
  • JSON(JavaScript Object Notation) 참고.
• 왜 RESTful API를 써는가
  • 서버 부하를 줄이고 클라이언트와 서버의 효율적인 통신을 위해 사용한다.
  • 서버의 확장에 용이하다.
  • 협업에서 서로 간의 소통을 원활하게 해준다.

REST API 설계 시 주의사항

1. REST API 디자인 시 URI는 정보의 자원을 표현해야 하며, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.
   • HTTP(Hyper Text Transfer Protocol) 참고.
   • 예시에서 GET은 자원에 대한 행위를, /post/1은 정보의 자원을 표현한다.

GET /post/1

2. URI의 마지막 문자로는 /를 포함하지 않아야 한다.

http://test.com/post/1/ (X)
http://test.com/post/1 (O)

3. 가독성을 위해 하이픈(-)을 사용하고, 밑줄(_)은 사용하지 않는다.

http://test.com/post_of_today (X)
http://test.com/post-of-today (O)

4. URI 경로에는 소문자를 사용한다.
   • 대문자에 따라 다른 리소스로 인식할 수 있기 때문이다.
   • RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하곤 대소문자를 구별한다.

http://test.com/POST/1/ (X)
http://test.com/post/1 (O)

5. URI에 파일 확장자를 포함시키지 않는다.

http://test.com/photo/test.jpg (X)
GET /photo HTTP/1.1 Host : test.com Accept: image/jpg

REST API 설계 시 리소스 간의 관계 표현

1. 소유 관계를 표현할 때 /resource/id/related-resource 형식으로 표현한다.

GET : /users/{userid}/info

• 관계가 복잡하다면 서브 리소스에 표현한다.
  • 사용자가 좋아하는 책 목록을 작성한다고 했을 때 id 뒤에 더 구체적으로 세분화한다.

GET : /users/{userid}/likes/books